Fix broken WSLCorePort channel after receive timeout#14455
Merged
chemwolf6922 merged 26 commits intomicrosoft:masterfrom Apr 21, 2026
Merged
Fix broken WSLCorePort channel after receive timeout#14455chemwolf6922 merged 26 commits intomicrosoft:masterfrom
chemwolf6922 merged 26 commits intomicrosoft:masterfrom
Conversation
chemwolf6922
requested review from
OneBlue,
benhillis,
Copilot,
craigloewen-msft and
justus-camp-microsoft
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes a broken channel state that occurs after a transaction timeout in WSL's socket-based IPC protocol. The issue (#14193, #14055) manifests after laptop sleep/hibernate, where a channel's expected sequence number gets desynchronized, causing all subsequent communication to fail until wsl --shutdown.
Changes:
- Replace independent sender/receiver sequence counters with an echo-back mechanism: the responder echoes back the request's sequence number in its reply, preventing desync after timeouts.
- Add a magic number field to
MESSAGE_HEADERfor early framing corruption detection, and skip stale (timed-out) replies in the receive loop. - Zero-initialize a
Replyunion inbinfmt.cppto ensure the newMessageMagicdefault initializer doesn't cause issues with rawread()calls.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
src/shared/inc/lxinitshared.h |
Added Magic constant and MessageMagic field to MESSAGE_HEADER; updated static_assert for new struct size. |
src/shared/inc/SocketChannel.h |
Rewrote send/receive sequence logic to echo-back model; added stale message skipping loop; replaced m_received_messages with m_expected_reply_sequence / m_pending_reply_sequence. |
src/shared/inc/socketshared.h |
Added magic number validation in RecvMessage before processing header. |
src/linux/init/binfmt.cpp |
Zero-initialized Reply union to handle new MessageMagic default member initializer. |
You can also share your feedback on Copilot code review. Take the survey.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes a broken channel state issue in WSL's SocketChannel that occurs after a transaction timeout (e.g., when resuming from sleep). Previously, a timeout would increment the expected message ID on the receiver side, but the sender wouldn't use that incremented ID, causing a permanent ID desync and locking the channel. The fix replaces independent sequence tracking with an echo-back mechanism where the responder echoes back the request's sequence number in its reply, and the requester skips stale replies from previously timed-out transactions.
Changes:
- Added a magic number field to
MESSAGE_HEADERand validated it inRecvMessageto detect framing corruption early. - Replaced independent sequence counters with an echo-back sequence mechanism in
SocketChannelusingm_expected_reply_sequenceandm_pending_reply_sequence, with a loop to skip stale replies. - Zero-initialized a union in
binfmt.cppto ensure the newMessageMagicfield is properly initialized when reading responses.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
src/shared/inc/lxinitshared.h |
Added Magic constant and MessageMagic field to MESSAGE_HEADER; updated static_assert for LX_GNS_SET_PORT_LISTENER size. |
src/shared/inc/socketshared.h |
Added magic number validation in RecvMessage after reading the header. |
src/shared/inc/SocketChannel.h |
Replaced send/receive sequence tracking with echo-back mechanism; added stale-reply skip loop; removed sequence parameter from ValidateMessageHeader. |
src/linux/init/binfmt.cpp |
Zero-initialized Reply union to ensure MessageMagic defaults correctly. |
You can also share your feedback on Copilot code review. Take the survey.
added 2 commits
March 17, 2026 17:31
…om:chemwolf6922/WSL into fix-broken-state-after-transaction-timeout
6 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
This PR aims to prevent SocketChannel protocol desynchronization after a transaction timeout (the “expected sequence” advancing while a late response with the previous sequence arrives), which can leave a channel in a permanently broken state.
Changes:
- Reworks SocketChannel sequencing to echo request sequence numbers in replies and discard stale replies.
- Adds new per-channel state (
m_expected_reply_sequence/m_pending_reply_sequence) to track request/reply sequencing. - Updates protocol error handling to validate type separately from sequencing.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (4)
src/linux/init/config.cpp:356
- The function signature now takes a
Transaction&for sending replies, but the argument documentation still refers toResponseChannel. Please update the comment block so the parameter names/descriptions match the new signature (e.g., describe that replies must be sent on the provided transaction).
void ConfigHandleInteropMessage(
wsl::shared::Transaction& Transaction,
wsl::shared::SocketChannel& InteropChannel,
bool Elevated,
gsl::span<gsl::byte> Message,
const MESSAGE_HEADER* Header,
const wsl::linux::WslDistributionConfig& Config)
/*++
Routine Description:
This routine handles a message received from a Linux client using init's
interop socket.
Arguments:
ResponseChannel - Supplies channel used to send responses.
InteropChannel - Supplies a channel to the host to be used for create
process requests.
src/linux/init/config.cpp:637
- The argument documentation still says
MessageFdis used to send the response, but the function now takes aSendResponsecallback. Please update the comment to reflect the new response mechanism to avoid confusion for future maintenance.
int ConfigInitializeInstance(const std::function<void(gsl::span<gsl::byte>&)>& SendResponse, gsl::span<gsl::byte> Buffer, wsl::linux::WslDistributionConfig& Config)
/*++
Routine Description:
This routine initializes the instance's externally controlled state, which
is received from the service.
N.B. When setting these values errors are treated as non-fatal to account
for unexpected distro state.
Arguments:
MessageFd - Supplies a file descriptor to send the response message.
Buffer - Supplies the message buffer.
src/linux/init/init.cpp:2687
- The doc comment still refers to a
Channelparameter for sending the terminate response, but the signature now takes aSendResultcallback. Please update the comment block to match the new parameters.
void InitTerminateInstance(gsl::span<gsl::byte> Buffer, const std::function<void(bool)>& SendResult, wsl::linux::WslDistributionConfig& Config)
/*++
Routine Description:
This routine processes a terminate instance request from the service.
Arguments:
Buffer - Supplies the message buffer.
Channel - Supplies a channel to send the response.
src/linux/init/main.cpp:3179
- The
ProcessMessagesignature now takes awsl::shared::Transaction&, but the argument comment block still describes aMessageFd/file descriptor used to send responses. Please update the documentation to reflect that replies should be sent via the provided transaction (or its underlying channel) rather than a raw fd.
int ProcessMessage(wsl::shared::Transaction& Transaction, LX_MESSAGE_TYPE Type, gsl::span<gsl::byte> Buffer, VmConfiguration& Config)
/*++
Routine Description:
This routine processes messages from the service.
Arguments:
MessageFd - Supplies a file descriptor to the socket on which the message was
received. This is used for operations that require responses, for example a
VHD eject request.
Contributor
Author
|
Hi @OneBlue . I updated the design to use transaction id + transaction step to better identify different messages. Please help review. Please also help verify if I updated all the correct pairs. Thanks. |
Contributor
Author
|
Hi @benhillis, I resolved the copilot comments. Could you please help take another look? Thanks. |
2 tasks
OneBlue
reviewed
Apr 16, 2026
Collaborator
OneBlue
left a comment
OneBlue
left a comment
There was a problem hiding this comment.
This looks great, very clean and should help us catch issues & recover from socket timeouts.
Couple minor comments, but I think we can merge this soon. Thank you for doing this !
OneBlue
approved these changes
Apr 20, 2026
shuaiyuanxx
added a commit
that referenced
this pull request
Apr 21, 2026
Resolve conflicts introduced by #14455 (transaction-based SocketChannel refactor) against the TraceLoggingActivity rework: - WslCoreInstance.cpp WaitForInitConfigResponse: keep the narrowed activity scope; switch the receive from m_initChannel->GetChannel().ReceiveMessage() to transaction.Receive() using the transaction that master starts for the preceding Send. - WslCoreVm.cpp SendLaunchInit: keep the activity scope and move the StartTransaction() + Send inside it. The transaction object is only used for this one-shot send (no matching receive on the same id within this function), so scoping it to the activity block preserves master's semantics.
benhillis
pushed a commit
that referenced
this pull request
Apr 21, 2026
Refactor the socket channel to resolve the broken state after a timeout: * Replace the sequence number with transaction id. And add transaction step in the message header. * The transaction and non-transaction messages are differentiated by the transaction step. * The old sequence number logic stays the same for non-transaction messages. * For transaction messages. The reply side will reply with the same id in the incoming transaction request. * For transaction messages. The receive loop will discard stale messages based on the transaction id.
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary of the Pull Request
This pattern shows up in multiple sleep -> wake -> wsl stuck reports:
In the current sequence number logic, the receive sequence will ++ without receiving any message. If timeout is allowed on the channel and it's not destroyed, the next receive will always get the N-1 message due to:
This will lock the channel in an unusable state.
This PR makes these changes to keep the WSLCorePort channels working after a receive timeout.
I tried my best to update all the applicable receive and sender ends to use the transaction logic. But please help double check I'm not missing anything. Since a mismatch will cause the transaction to always fail.
PR Checklist
Closes: WSL2 regularly crashes on waking up from sleep #14193 WSL 2.6.3.0: Terminal crash after hibernation/sleep with [process exited with code 1] #14055 Error code: Wsl/Service/E_UNEXPECTED #14014
Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
Tests: Added/updated if needed and all pass
All but 8 unit test fails. Where 6 of them failed because of GPO settings or powershell issues. 2 of them (CGroupv1 and CaseSensitivity) failed but seems unrelated to the changes. I have appended logs for those failed tests in the end.
I'm also dog fooding this build right now.
Localization: All end user facing strings can be localized
Dev docs: Added/updated if needed
Documentation updated: If checked, please file a pull request on our docs repo and link it here: #xxx
Detailed Description of the Pull Request / Additional comments
Validation Steps Performed
Failed unit tests